Overall model structure

MtM ABM documentation

Author

David O’Sullivan

Published

February 14, 2025

Date Changes
2025-02-14 Initial post.

The model interface

At time of writing the model GUI appears as below (click on it for a closer look):

Column 1

Controls on the left-hand side are primarily starting and running the model and controlling display of visual elements.

Column 2

The map area shows LUC (more intense colours are better land) and land use according to the following key:

  • Greens Forest
  • Blues Dairy
  • Oranges Sheep and beef (SNB)
  • Purples Crops

Farms are delineated in black and their current profit is shown by a circle scaled by the level of profit. If ‘in the black’ the circle is coloured to match dominant land use on the farm. If the farm is losing money (‘in the red’) the circle is coloured red.

Holdings are delineated in grey and shown by squares scaled and coloured in the same way as farms.

Column 3

The column of controls immediately to the right of the map area mostly controls model initialisation, in particularly allowing for initialisation from controlled random number seeds to allow for repeatability of results and exploration of the details of any findings. Two important settings are controlled by ‘sliders’:

  • sigmoid-slope controls the rate of change of probabilities of adoption of intervention in response to push and pull factors. This is uncalibrated at present. A potential extension of the model would allow different levels of this control for different ‘nudge’ or market effects.

  • carbon-price the model carbon price (which impacts calculation of farm costs)

Column 4

The column of controls on the right of the model provides some tracking plots (farmer ages, overall land on which different interventions have been adopted, and overall land in different land uses), and also some high level controls as follows:

  • consider-landuse-change-on-succession: If On when a farmer is succeeded by a new entrant the new farmer considers a change in (all of farm) land use
  • prioritise-forestry-set-aside: If On when a holding is unprofitable only forestry is considered as new land use; other land uses are considered if this option is Off
  • apply-severity-of-losses`: If On losses occurring across more of the farm (by area) make whole of farm conversion of land use more likely
  • apply-suitability`: If On suitability of LUC of holdings is taken into account when land use change is undertaken; If **Off* land use change disregards LUC
  • region: Specifies data/spatial subfolder of GIS input files
  • scenario: Specifies data/market subfolder of market input files

Model elements

Clearly, there is a lot going on here. The easiest way to get a handle on it is through the main model elements and their attributes and behaviours.

Land use

Each unit of land in the model, and the aggregations into holdings or farms has a land use, which is one of "Crop", "Dairy", "Forest", or "SNB". This classification could be made more detailed, although some work would be required on visualization aspects of the model to accommodate the change. Note: Applied to grid cells representing the land in the model, land use is the landuse attribute. Applied to farmers, farms, or holdings it is farm-type. For holdings the two will always match exactly (all cells in a holding will be the same land use), but for farmers and farms not all associated cells need be in the same land use.

Management interventions

A list of potential management interventions, such as e.g., "Build_Wetland", "Clean_Races", "Farm_Plan", "Join_ETS", or "Riparian_Planting". These have associated impacts on costs, yields and emissions as set out in the intervention-impacts.csv file.

The land

The land is represented by a square grid of cells (in NetLogo terminology ‘patches’). Each grid cell represents a notional 1 hectare, although the model’s spatial and temporal scales remain a little fuzzy at present. Each cell ‘knows’ its owning farmer and the holding and farm of which it is a part, although this information at the grid cell level is used mostly during model initialiasation. Each cell also has a landuse attribute which is one of the land uses represented, and a luc-code, an integer between 1 and 8 (inclusive).

Farmers

Farmers are the only decision-making agents in the model even as other model elements (farms and holdings) are coded as ‘agents’ (everything in NetLogo is an agent1).

Farmers have the following attributes:

  • farm-type: one of the land uses in the model, i.e. one of "Crop", "Dairy", "Forest", or "SNB"
  • my-farm: this farmer’s farm
  • my-holdings: this farmer’s holdings
  • the-land: a list of grid cells that compose the farm
  • age: age in years. Affects likelihood of farmer leaving and being succeeded by a new farmer.
  • succession-stage: how many ‘new farmers’ or ‘which generation’ of farmer this one is on this farm. We don’t spawn new farmers on succession, we just change their settings and increment this attribute
  • disposition: one of "for-profit", "pro-social", or "pro-environmental". Not currently used.
  • industry-links and local-links: other farmers connected to this one, that might influence their decisions. The model machinery to enable this is present but not currently used.

Key actions run by farmers include:

  • age-and-succeed-farmer: each model tick farmers age by one year, and with probability \frac{1}{91-\mathrm{age}} exit the industry and are replaced by a new farmer that may be of different disposition, a different age (not necessarily younger, but probably), and if any holdings are currently loss-making will consider all of farm land use change.
  • consider-farm-type-change and consider-holdings-farm-type-change: as detailed in Farmer decisions about land use farmers may decide to change the land use of a whole farm, or change the land use of individual holdings.
  • make-farm-type-changes: if a decision is taken to change land use on a farm or any of its holdings the farmer coordinates necessary updates to the model state.
  • consider-management-changes and make-management-changes: consider possible management interventions for adoption and implement them (or not) as detailed in Farmer decisions about management interventions.

Farms

Farms don’t do much of anything since holdings were added to the model. This is reflected in the fact that their only attributes are the self-explanatory the-land, farm-type, and my-farmer. A potential extension of the model (partly implemented) records the losses-record of a farm and this impacts the willingness of farmer’s to consider land use change, so that an immediate all-of-farm change in land use only becomes likely if losses occur repeatedly over time.

Holdings

Holdings are subfarm level units at which management interventions and land use changes are implemented.

Holdings have the following attributes:

  • farm-type: one of the land uses in the model, i.e. one of "Crop", "Dairy", "Forest", or "SNB"
  • my-farmer: the farmer who owns this holding
  • my-farm: the farm of which this holding is a part
  • the-land: a list of grid cells that compose the farm
  • landuse-luc-profile: a cross tabulation of the number of grid cells (i.e., hectares) of land in the holding by land use and LUC. In the current implementation since holdings are defined by land use and LUC only one entry in the table will be non-zero! However, as detailed in Calculation of farm income this allows for more complex holding structures—most likely with a range of LUC across a holding. A farmer can sum these matrices to get a picture of the overall composition of the farm.
  • current-profit, current-income, and current-costs: profit, income, and costs of the holding as detailed in Calculation of farm income.
  • my-mgmt-interventions: a list of boolean flags indicating which management interventions have been adopted on this holding.
  • avail-mgmt-interventions: a list of boolean flags indicating which management interventions remain available to this holding for possible adoptions.

Key actions run by holdings (at the behest of farmers!) are:

  • holding-change-farm-type and implement-intervention: bookkeeping functions to pass changes in land use down to grid cells and update the lists of adopted and available interventions.
  • get-intervention-score: scores interventions under consideration based on impact on costs and income as detailed in Farmer decisions about management interventions.
  • get-holding-income and get-holding-costs: calculate holding income and costs as detailed in Calculation of farm income
  • get-cost-after-intervention, get-yield-after-intervention, and get-emissions-after-intervention: calculates what the income or yield or emissions of the holding would be if a specified intervention were to be implemented as part of the decision making process around management interventions, as detailed in Farmer decisions about management interventions.

Organisation of model files

Code

To make managing model source code a little easier the code is broken into a main .nlogo file and a number of NetLogo source .nls files. Unfortunately the built in IDE for NetLogo is rather primitive, so this breakdown is not perfect, but it at least keeps the size of each source file manageable (a few hundred lines at most), where a monolithic flat file would be 2000+ lines. The files are as follows:

Filename Purpose
abm-working.nlogo Definition of globals, setup and main model loop, model reset code
mtm-read-files.nls Reading of market setting files into tables and conversion to matrices
mtm-geography.nls Setup of model geography, whether from GIS files or random
mtm-farmer.nls Initialisation and maintenance of farmer agents, primarily procedures for choosing among options for land use change / management interventions
mtm-farm.nls Initialisation and maintenance of farm agents
mtm-holding.nls Initialisation and maintence of holding agents, primarily calculation of income and costs
mtm-plots.nls Plotting of some model statistics for interactive exploration
mtm-render.nls Visual rendering of model state

In addition the files list-utils.nls, distribution-utils.nls (both from my netlogo-utils project), and mtm-utils.nls collect together a large number of utility functions of general use to all the other model components.

Data

A key idea underpinning model development was to avoid hard coding dozens, or even hundreds of settings into the model code. To that end a data folder in the same directory as the model source code has subfolders market and spatial themselves with subfolders containing model input files that can specify scenarios whether catchment-based (the spatial folder) or market-based (the market folder).

Market

Each ../data/market/<scenario-name> subfolder contains a collection of files that configure aspects of the market, which together form a scenario.

Filename Purpose
farmer-threshold-matrix.csv Baseline probabilities of adoption by farmers of available management interventions by land use
intervention-impacts.csv Impact on yields, costs, and emissions per ha. by management intervention and land use
conversion-probabilities.csv Relative probability of conversion between the different land uses
suitabilities.csv Binary (yes/no) suitability by land use capability for each land use
input-costs.csv Mean and st dev. of costs per ha. of inputs by land use and land use capability
commodity-yields.csv Mean and st dev. of yields (in appropriate units) per ha. of output by land use and land use capability
prices.csv Market price (per unit of output) by land use
ghg-emissions.csv Mean and st dev. of GHG emissions (in appropriate units) per ha. of output by land use and land use capability

The first of these files (farmer-threshold-matrix.csv) effectively defines the available land use types and interventions and additional rows or columns could be added to it to further detail the model’s representation. Note: Extending the model in this way to add interventions is trivial; adding additional land uses will require additional code to deal with visualisation aspects.

The first 4 files effectively define the decision space of farmers in the model. The latter 4 define the market constraints (costs, yields, prices, emissions).

Geographical setting

The geographical setting of the model can be initialised randomly or from GIS files (controlled by a switch in the model GUI).

Random initialisation first sets up a land use capability (LUC) landscape either using iterative smoothing2, pp 60-63), or using a voter model3, then randomly distributes farmers across the landscape assigning them a farm based on Voronoi polygons4 and breaking the farm into sub-farm level holdings based on contiguouse areas of the same LUC.

Initialisation from GIS files uses a parcels.shp shapefile and luc.asc raster file to specify define respectively the farms and LUC landscape of the model. Farms are again subdivided into holdings based on LUC. Different catchments can be applied by providing these files in a folder data/spatial/<region-name>. Model development has been based on data for the Rangitaiki catchment to test this setup. Currently initialisation from files sets land use randomly (no such attribute is available in the parcels.shp file), but we anticipate that ‘localisation’ of the model to particular catchments will be relatively straightforward given appropriate spatial data files.

Footnotes

  1. Called ‘turtles’ in NetLogo land due to NetLogo’s origins in the Logo programming language which introduced ‘turtle graphics’. See Resnick M. 1994. Turtles, Termites, and Traffic Jams: Explorations in Massively Parallel Microworlds. Cambridge MA: MIT Press.↩︎

  2. See pages 60-63 in O’Sullivan D and GLW Perry. 2013. Spatial Simulation: Exploring Pattern and Process. Chichester, UK: Wiley.↩︎

  3. See pages 80-81 in O’Sullivan D and GLW Perry. 2013. Spatial Simulation: Exploring Pattern and Process. Chichester, UK: Wiley.↩︎

  4. Okabe A, B Boots, K Sugihara, and SN Chiu. 2000. Spatial Tessellations: Concepts and Applications of Voronoi Diagrams. 2nd edn. Chichester, UK: Wiley.↩︎